Add instances() API for primitive instancing by aashu2006 · Pull Request #8952 · processing/p5.js

aashu2006 · 2026-06-22T01:21:33Z

Addresses #8911

Changes

Add a new instances(count) API for primitive instancing in WebGL.
Support instancing for primitives including sphere(), box(), plane(), ellipsoid(), cylinder(), cone(), and torus().
Preserve existing model(geometry, count) behavior while supporting instances(count).model(geometry)
Forward instance counts through the existing retained-geometry rendering pipeline.
Add TypeScript support for the new InstancesWrapper API.
Add unit tests for primitive/model instancing and explicit count precedence.
Add WebGL and WebGPU visual tests with reference snapshots.
Update the documentation example to use p5.strands and instanceIndex().

PR Checklist

npm run lint passes
Inline reference is included / updated
Unit tests are included / updated

p5-bot · 2026-06-22T19:23:13Z

Continuous Release

CDN link

https://raw.esm.sh/pr/p5@1b0fdde/lib/p5.min.js

Published Packages

https://pkg.pr.new/p5@1b0fdde

Commit hash: f134f1d

Previous deployments

`2d446bf`

`f35f290`

`057f727`

This is an automated message.

davepagurek · 2026-06-25T16:15:15Z

  model(model, count = 1) {
+    // Use _instanceCount only when count was NOT explicitly passed.
+    // arguments.length distinguishes model(geom) from model(geom, 1).
+    if (arguments.length < 2 && this._instanceCount !== undefined) {


It's a tad unintuitive seeing a default value for count and having this condition -- at least, it's not obvious whether or not it's included. Thoughts on leaving out the default value for count, and then we can do something like:

count = count ?? this._instanceCount ?? 1 ``

I updated this to use count = count ?? this._instanceCount ?? 1; instead.

davepagurek · 2026-06-25T16:18:07Z

+   * @method instances
+   * @param  {Number} count number of instances to draw. Must be a positive
+   *   integer.
+   * @returns {Object} an object with methods `sphere`, `box`, `plane`,


For TypeScript, if we just call it Object then all methods chained onto it will look like type errors. Take a look at the types added for the different p5.strands hooks in #8644, they add typedefs that add the different methods

I did follow the pattern from #8644 and updated the typedefs, this also required a small fix in the type generator so the optional parameters are generated correctly.

davepagurek · 2026-06-25T16:18:31Z

+    this._assert3d('instances');
+
+    if (typeof count !== 'number' || !isFinite(count) || count < 1) {
+      console.log(


This should probably be an FES message so that it's disabled when FES is disabled

updated this to use the Friendly Error System.

davepagurek · 2026-06-25T16:19:52Z

+        '🌸 p5.js says: instances() requires a positive integer count.' +
+        ' Clamping to 1.'
+      );
+      count = Math.max(1, Math.round(count) || 1);


is there an input where we don't just set it directly to 1 here? might be more robust to do that

simplified this to clamp directly to 1.

davepagurek · 2026-06-25T16:22:49Z

+      } finally {
+        r._instanceCount = undefined;
+      }
+      return p;


Is the intention to be able to chain multiple things? If so I think this return value would need to be the returned object below instead of p. If not, we probably don't need to return p (or track p at all)

I made it a terminal draw call and removed the return value to avoid that misleading chaining behavior.

davepagurek · 2026-06-25T16:23:30Z

+   * }
+   * function draw() {
+   *   background(200);
+   *   instances(10).sphere(20);


These currently all draw on top of each other since now shader is present, can we add a p5.strands shader to make use of the instances?

updated the example to use p5.strands and instanceIndex so the instancing behavior is visible.

davepagurek · 2026-06-25T16:23:46Z

+   * <div>
+   * <code>
+   * // Draw 10 spheres in a single instanced draw call.
+   * // A custom shader reads gl_InstanceID to offset each sphere.


We should probably use strands and not mention GLSL-specific things

updated the wording to use the strands API.

davepagurek

This is looking good! I left some comments. Once the example in the docs is more complete, could we add it as a visual test in both webgl and webgpu modes to have an end-to-end test for each?

aashu2006 · 2026-06-25T19:31:48Z

@davepagurek Done! I used the updated example as the basis and added the corresponding visual tests for both WebGL and WebGPU.

davepagurek

Thanks for the updates! Some thoughts:

Should the parameters be recursively passed into convertTypeToTypeScript to handle all the same cases there? (Does doing that break anything?)
For the visual tests to work, you'll need to run it first locally and commit the added snapshots so that CI has something to compare to in the future.
There are some other shape drawing methods that aren't added yet, such as plane, line, etc. Maybe worth looking through the 3d_primitives file and seeing if anything else there should be added?

aashu2006 · 2026-06-25T20:13:31Z

thanks for the quick feedback @davepagurek

I pushed another update, also added the visual test snapshots this time, my bad for missing them in the previous push.

I looked into the convertTypeToTypeScript() suggestion as well. It already handles OptionalType recursively, but convertFunctionTypeForInterface() still needs the parameter name and optionality first, so I kept the unwrapping there before passing the type through convertTypeToTypeScript().

I also took another pass through 3d_primitives.js. The omitted ones like line() use the immediate-mode path, so they don't make use of _instanceCount. I did notice a few retained-geometry shapes like triangle(), rect(), quad(), and ellipse()/arc() could technically be supported too. Would you want instances() to cover those as well, or keep it focused on the current set?

davepagurek · 2026-06-25T20:32:37Z

Sounds good, thanks for looking into the typescript stuff!

Yeah, let's see if we can support all the shapes if we can.

aashu2006 · 2026-06-25T21:36:57Z

Thanks, I updated the remaining retained-geometry shapes as well. I think that should cover everything from my side now, but happy to make any further changes if needed 🙂

davepagurek

thanks for the updates! I think we can support line and other APIs that go through begin/endShape by updating the count parameter in endShape to do what you've done for model.

As a list thing, I think we use instanceID() in some examples. If you search for instanceID() in the codebase to find those, can we update those to use your new syntax and avoid buildGeometry if they're just drawing a sphere or something to simplify them?

aashu2006 · 2026-06-26T16:11:57Z

I added support for immediate mode APIs by forwarding instance count through endShape(), so line(), point(), bezier(), and spline() now work with instances(). I also updated the examples to use instanceIndex and instances(), and added visual tests for both WebGL and WebGPU.

For curve(), I kept it conditional since spline() is the standard API in 2.x, while curve() is only available in compatibility setups.

aashu2006 changed the title ~~Instances api~~ Add instances() API for primitive instancing Jun 22, 2026

davepagurek reviewed Jun 25, 2026

View reviewed changes

aashu2006 added 3 commits June 26, 2026 00:52

Add instances() API for primitive instancing

cbb4bd4

Add tests for instances() API

8d70be1

Address review feedback for instances API

83e3a1d

aashu2006 force-pushed the instances-api branch from 057f727 to 83e3a1d Compare June 25, 2026 19:23

davepagurek reviewed Jun 25, 2026

View reviewed changes

Fix and complete visual tests for instances API

f35f290

Expand instances API to additional retained geometry shapes

2d446bf

davepagurek reviewed Jun 26, 2026

View reviewed changes

Support instancing for immediate-mode primitives

f134f1d

Uh oh!

Uh oh!

Conversation

aashu2006 commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Checklist

Uh oh!

p5-bot Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Continuous Release

CDN link

Published Packages

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davepagurek left a comment

Choose a reason for hiding this comment

Uh oh!

aashu2006 commented Jun 25, 2026

Uh oh!

davepagurek left a comment

Choose a reason for hiding this comment

Uh oh!

aashu2006 commented Jun 25, 2026

Uh oh!

davepagurek commented Jun 25, 2026

Uh oh!

aashu2006 commented Jun 25, 2026

Uh oh!

davepagurek left a comment

Choose a reason for hiding this comment

Uh oh!

aashu2006 commented Jun 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aashu2006 commented Jun 22, 2026 •

edited

Loading

p5-bot Bot commented Jun 22, 2026 •

edited

Loading